
<!doctype html>
<html lang="en" class="no-js">
  <head>
    
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width,initial-scale=1">
      
      
      
      
        <link rel="prev" href="../loadtest-jmeter/">
      
      
      
      <link rel="icon" href="../../assets/images/favicon.png">
      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.6.20">
    
    
      
        <title>Issues·Root Cause·Fixes - Robot Scheduling Docs</title>
      
    
    
      <link rel="stylesheet" href="../../assets/stylesheets/main.e53b48f4.min.css">
      
        
        <link rel="stylesheet" href="../../assets/stylesheets/palette.06af60db.min.css">
      
      


    
    
      
    
    
      
        
        
        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
        <style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
      
    
    
      <link rel="stylesheet" href="../../styles.css">
    
    <script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
    
      

    
    
    
  </head>
  
  
    
    
      
    
    
    
    
    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="cyan">
  
    
    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
    <label class="md-overlay" for="__drawer"></label>
    <div data-md-component="skip">
      
        
        <a href="#issuesroot-causefixes" class="md-skip">
          Skip to content
        </a>
      
    </div>
    <div data-md-component="announce">
      
    </div>
    
    
      

  

<header class="md-header md-header--shadow" data-md-component="header">
  <nav class="md-header__inner md-grid" aria-label="Header">
    <a href="../" title="Robot Scheduling Docs" class="md-header__button md-logo" aria-label="Robot Scheduling Docs" data-md-component="logo">
      
  
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>

    </a>
    <label class="md-header__button md-icon" for="__drawer">
      
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
    </label>
    <div class="md-header__title" data-md-component="header-title">
      <div class="md-header__ellipsis">
        <div class="md-header__topic">
          <span class="md-ellipsis">
            Robot Scheduling Docs
          </span>
        </div>
        <div class="md-header__topic" data-md-component="header-topic">
          <span class="md-ellipsis">
            
              Issues·Root Cause·Fixes
            
          </span>
        </div>
      </div>
    </div>
    
      
        <form class="md-header__option" data-md-component="palette">
  
    
    
    
    <input class="md-option" data-md-color-media="" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="cyan"  aria-label="深色模式"  type="radio" name="__palette" id="__palette_0">
    
      <label class="md-header__button md-icon" title="深色模式" for="__palette_1" hidden>
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m17.75 4.09-2.53 1.94.91 3.06-2.63-1.81-2.63 1.81.91-3.06-2.53-1.94L12.44 4l1.06-3 1.06 3zm3.5 6.91-1.64 1.25.59 1.98-1.7-1.17-1.7 1.17.59-1.98L15.75 11l2.06-.05L18.5 9l.69 1.95zm-2.28 4.95c.83-.08 1.72 1.1 1.19 1.85-.32.45-.66.87-1.08 1.27C15.17 23 8.84 23 4.94 19.07c-3.91-3.9-3.91-10.24 0-14.14.4-.4.82-.76 1.27-1.08.75-.53 1.93.36 1.85 1.19-.27 2.86.69 5.83 2.89 8.02a9.96 9.96 0 0 0 8.02 2.89m-1.64 2.02a12.08 12.08 0 0 1-7.8-3.47c-2.17-2.19-3.33-5-3.49-7.82-2.81 3.14-2.7 7.96.31 10.98 3.02 3.01 7.84 3.12 10.98.31"/></svg>
      </label>
    
  
    
    
    
    <input class="md-option" data-md-color-media="" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="cyan"  aria-label="亮色模式"  type="radio" name="__palette" id="__palette_1">
    
      <label class="md-header__button md-icon" title="亮色模式" for="__palette_0" hidden>
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 7a5 5 0 0 1 5 5 5 5 0 0 1-5 5 5 5 0 0 1-5-5 5 5 0 0 1 5-5m0 2a3 3 0 0 0-3 3 3 3 0 0 0 3 3 3 3 0 0 0 3-3 3 3 0 0 0-3-3m0-7 2.39 3.42C13.65 5.15 12.84 5 12 5s-1.65.15-2.39.42zM3.34 7l4.16-.35A7.2 7.2 0 0 0 5.94 8.5c-.44.74-.69 1.5-.83 2.29zm.02 10 1.76-3.77a7.131 7.131 0 0 0 2.38 4.14zM20.65 7l-1.77 3.79a7.02 7.02 0 0 0-2.38-4.15zm-.01 10-4.14.36c.59-.51 1.12-1.14 1.54-1.86.42-.73.69-1.5.83-2.29zM12 22l-2.41-3.44c.74.27 1.55.44 2.41.44.82 0 1.63-.17 2.37-.44z"/></svg>
      </label>
    
  
</form>
      
    
    
      <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
    
    
      <div class="md-header__option">
  <div class="md-select">
    
    <button class="md-header__button md-icon" aria-label="Select language">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m12.87 15.07-2.54-2.51.03-.03A17.5 17.5 0 0 0 14.07 6H17V4h-7V2H8v2H1v2h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2zm-2.62 7 1.62-4.33L19.12 17z"/></svg>
    </button>
    <div class="md-select__inner">
      <ul class="md-select__list">
        
          <li class="md-select__item">
            <a href="../../issues-rca/" hreflang="zh" class="md-select__link">
              中文
            </a>
          </li>
        
          <li class="md-select__item">
            <a href="./" hreflang="en" class="md-select__link">
              English
            </a>
          </li>
        
      </ul>
    </div>
  </div>
</div>
    
    
      
      
        <label class="md-header__button md-icon" for="__search">
          
          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
        </label>
        <div class="md-search" data-md-component="search" role="dialog">
  <label class="md-search__overlay" for="__search"></label>
  <div class="md-search__inner" role="search">
    <form class="md-search__form" name="search">
      <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
      <label class="md-search__icon md-icon" for="__search">
        
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
        
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
      </label>
      <nav class="md-search__options" aria-label="Search">
        
        <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
          
          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
        </button>
      </nav>
      
    </form>
    <div class="md-search__output">
      <div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
        <div class="md-search-result" data-md-component="search-result">
          <div class="md-search-result__meta">
            Initializing search
          </div>
          <ol class="md-search-result__list" role="presentation"></ol>
        </div>
      </div>
    </div>
  </div>
</div>
      
    
    
      <div class="md-header__source">
        <a href="https://gitee.com/Jimmy-chen-zheng/robot-interface-demo.git" title="Go to repository" class="md-source" data-md-component="source">
  <div class="md-source__icon md-icon">
    
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.0.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
  </div>
  <div class="md-source__repository">
    Gitee
  </div>
</a>
      </div>
    
  </nav>
  
</header>
    
    <div class="md-container" data-md-component="container">
      
      
        
          
        
      
      <main class="md-main" data-md-component="main">
        <div class="md-main__inner md-grid">
          
            
              
              <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">
                    



  

<nav class="md-nav md-nav--primary md-nav--integrated" aria-label="Navigation" data-md-level="0">
  <label class="md-nav__title" for="__drawer">
    <a href="../" title="Robot Scheduling Docs" class="md-nav__button md-logo" aria-label="Robot Scheduling Docs" data-md-component="logo">
      
  
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg>

    </a>
    Robot Scheduling Docs
  </label>
  
    <div class="md-nav__source">
      <a href="https://gitee.com/Jimmy-chen-zheng/robot-interface-demo.git" title="Go to repository" class="md-source" data-md-component="source">
  <div class="md-source__icon md-icon">
    
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.0.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
  </div>
  <div class="md-source__repository">
    Gitee
  </div>
</a>
    </div>
  
  <ul class="md-nav__list" data-md-scrollfix>
    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Dashboard
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../overview/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Overview
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../live-demo/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Live Demo
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../config-nacos/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Configuration Center (Nacos)
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../observability/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Observability (SkyWalking)
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../stability-sentinel/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Stability (Sentinel)
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../mq-async/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Async (RabbitMQ)
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../docker-deploy/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Containerized Deployment (Docker)
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
  
  
    <li class="md-nav__item">
      <a href="../loadtest-jmeter/" class="md-nav__link">
        
  
  
  <span class="md-ellipsis">
    Load Test (JMeter)
    
  </span>
  

      </a>
    </li>
  

    
      
      
  
  
    
  
  
  
    <li class="md-nav__item md-nav__item--active">
      
      <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
      
      
        
      
      
        <label class="md-nav__link md-nav__link--active" for="__toc">
          
  
  
  <span class="md-ellipsis">
    Issues·Root Cause·Fixes
    
  </span>
  

          <span class="md-nav__icon md-icon"></span>
        </label>
      
      <a href="./" class="md-nav__link md-nav__link--active">
        
  
  
  <span class="md-ellipsis">
    Issues·Root Cause·Fixes
    
  </span>
  

      </a>
      
        

<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
  
  
  
    
  
  
    <label class="md-nav__title" for="__toc">
      <span class="md-nav__icon md-icon"></span>
      Table of contents
    </label>
    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#0-go-live-definitions-load-test-baseline" class="md-nav__link">
    <span class="md-ellipsis">
      0. Go-live Definitions &amp; Load-test Baseline
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#1-gateway-nacos-sentinel" class="md-nav__link">
    <span class="md-ellipsis">
      1. Gateway / Nacos / Sentinel
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#2-observability-infrastructure" class="md-nav__link">
    <span class="md-ellipsis">
      2. Observability &amp; Infrastructure
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#3-asynchrony-idempotency" class="md-nav__link">
    <span class="md-ellipsis">
      3. Asynchrony &amp; Idempotency
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#4-code-frontend-ruoyi-vue" class="md-nav__link">
    <span class="md-ellipsis">
      4. Code &amp; Frontend (RuoYi + Vue)
    </span>
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#5-conventions-governance-unified-naming-traceability" class="md-nav__link">
    <span class="md-ellipsis">
      5. Conventions &amp; Governance (Unified Naming &amp; Traceability)
    </span>
  </a>
  
</li>
      
    </ul>
  
</nav>
      
    </li>
  

    
  </ul>
</nav>
                  </div>
                </div>
              </div>
            
            
          
          
            <div class="md-content" data-md-component="content">
              <article class="md-content__inner md-typeset">
                
                  



<h1 id="issuesroot-causefixes">Issues·Root Cause·Fixes<a class="headerlink" href="#issuesroot-causefixes" title="Permanent link">&para;</a></h1>
<blockquote>
<p>Environment: RuoYi-Cloud (ruoyi-modules-robot / ruoyi-api-robot), Gateway unified entry <code>/external/gs/**</code>;<br />
Nacos registry &amp; config, Sentinel dynamic rules, SkyWalking full-link, optional RabbitMQ async; Docker Compose one-click delivery.</p>
</blockquote>
<hr />
<h2 id="0-go-live-definitions-load-test-baseline">0. Go-live Definitions &amp; Load-test Baseline<a class="headerlink" href="#0-go-live-definitions-load-test-baseline" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Ambiguous definitions &amp; baseline</strong><br />
<strong>Symptom</strong>: Different teammates use inconsistent definitions for “success/failure” and whether 429 counts, causing metric misinterpretation.<br />
<strong>Fix</strong>: Standardize definitions &amp; baseline:  </li>
<li><strong>Dry-Run / consumers disabled</strong> load-test baseline: 100 QPS × 3 minutes; count 200/429 as success (to validate gateway rate-limit/stability).  </li>
<li><strong>Observed metrics</strong>: P95/P99, Throughput, Error%, queue backlog, SkyWalking Success Rate.  </li>
<li>
<p><strong>Sample result</strong>: 18,035 samples <strong>P95 = 6 ms</strong>, <strong>P99 ≈ 10 ms</strong>, <strong>Error = 0</strong>, Throughput ≈ <strong>100.2/s</strong> (consistent across rounds).</p>
</li>
<li>
<p><strong>Rollback &amp; cold-start not quantifiable</strong><br />
<strong>Fix</strong>: Persist to a “Change Log”:  </p>
</li>
<li><strong>Cold start</strong>: Docker Compose + initial SQL → <strong>≤ 12 minutes</strong> to bring up a new env;  </li>
<li><strong>Rollback</strong>: after microservices split <strong>≤ 5 minutes</strong> (revert image/config).</li>
</ul>
<hr />
<h2 id="1-gateway-nacos-sentinel">1. Gateway / Nacos / Sentinel<a class="headerlink" href="#1-gateway-nacos-sentinel" title="Permanent link">&para;</a></h2>
<ul>
<li>
<p><strong>Nacos stuck at STARTING</strong><br />
<strong>Cause</strong>: Persistent <strong>MySQL version/charset mismatch</strong> or init SQL not imported.<br />
<strong>Fix</strong>: Complete <code>spring.datasource.*</code>, import official/project init scripts; align versions &amp; images (recommend <strong>2.2.x</strong>).</p>
</li>
<li>
<p><strong>Gateway 404 / Swagger “Try it out” fails</strong><br />
<strong>Cause</strong>: <code>StripPrefix/Path</code> inconsistent with downstream <strong><code>context-path</code></strong>; route not updated after prefix change.<br />
<strong>Fix</strong>: Unify path strategy; if needed <strong>remove</strong> <code>context-path</code> or adjust Strip rules accordingly; deprecate old prefixes after gray rollout.</p>
</li>
<li>
<p><strong>Rate-limit paths inconsistent, rules not matched</strong><br />
<strong>Cause</strong>: <code>@SentinelResource</code> <strong>scattered in Controllers</strong>, inconsistent resource names.<br />
<strong>Fix</strong>: Consolidate into <strong><code>GsOpenApiServiceImpl</code></strong>; standardize resource naming and map one-to-one with Nacos rules<br />
  (e.g., <code>ruoyi-gateway-gw-api-defs/gw-flow/gw-degrade</code>).</p>
</li>
<li>
<p><strong>Sentinel rules not applied / empty group</strong><br />
<strong>Cause</strong>: Missing <code>sentinel-datasource-nacos</code> dependency, or <strong>DataId/Group vs JSON</strong> mismatch.<br />
<strong>Fix</strong>: Add dependency; verify the triple <code>{AppName, DataId, Group}</code> and JSON structure; before load test raise gateway thresholds to avoid premature 429 blocking.</p>
</li>
<li>
<p><strong>CORS preflight blocked</strong><br />
<strong>Cause</strong>: <strong>OPTIONS</strong> not allowed or response headers missing.<br />
<strong>Fix</strong>: Configure global CORS: allow required <code>Origin/Headers/Methods</code>, expose necessary headers; explicitly allow <strong>OPTIONS</strong>.</p>
</li>
</ul>
<hr />
<h2 id="2-observability-infrastructure">2. Observability &amp; Infrastructure<a class="headerlink" href="#2-observability-infrastructure" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>No Gateway spans / logs missing <code>traceId</code></strong><br />
<strong>Cause</strong>: <strong>SCG/WebFlux plugin</strong> not loaded; <code>-javaagent</code> not injected; Logback lacks MDC.<br />
<strong>Fix</strong>:  </li>
<li>Put <code>apm-spring-cloud-gateway-3.x-plugin</code> into <strong>plugins</strong>;  </li>
<li>Start with <code>-javaagent:/path/to/agent/agent.jar</code>;  </li>
<li>
<p>Add <code>%X{traceId}</code> to Logback pattern; raise sampling rate during load tests, reduce noise in production per QPS.</p>
</li>
<li>
<p><strong>Docker: MySQL port conflict / no data on first run</strong><br />
<strong>Cause</strong>: Host occupying <code>3306</code> or init SQL not imported.<br />
<strong>Fix</strong>: Adjust port mapping or stop host MySQL; <strong>pre-import SQL in compose</strong>; add <code>healthcheck</code> and use <code>depends_on.condition=service_healthy</code> upstream.</p>
</li>
<li>
<p><strong>In-container access fails (misusing host <code>localhost</code>)</strong><br />
<strong>Cause</strong>: Containers treat host address as local.<br />
<strong>Fix</strong>: Container-to-container calls use <strong>serviceName:port</strong>; to access host on Win/Mac, use <code>host.docker.internal</code>.</p>
</li>
<li>
<p><strong>Dependency/plugin conflicts (e.g., Reactor Netty)</strong><br />
<strong>Cause</strong>: Spring Boot/Cloud matrix misaligned with dependencies.<br />
<strong>Fix</strong>: Lock a version matrix; include only needed gateway/webflux/skywalking plugins and verify compatibility.</p>
</li>
</ul>
<hr />
<h2 id="3-asynchrony-idempotency">3. Asynchrony &amp; Idempotency<a class="headerlink" href="#3-asynchrony-idempotency" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Queue keeps growing during load test / duplicate consumption</strong><br />
<strong>Cause</strong>: Demo env <strong>consumers disabled (Dry-Run)</strong> or missing <strong>prefetch/manual ack</strong>; retries without upper bound.<br />
<strong>Fix</strong>:  </li>
<li>Load-test definition: with consumers off, only validate ingress &amp; observability; backlog is acceptable;  </li>
<li>Production: enable consumers, set <code>prefetch = n</code>, <strong>manual ack</strong>, failures go to <strong>DLQ</strong>;  </li>
<li>
<p>For write operations add <strong>idempotency keys</strong>; timeouts/retries must <strong>not amplify failures</strong>.</p>
</li>
<li>
<p><strong>RestTemplate pile-up / retries amplify issues</strong><br />
<strong>Cause</strong>: No timeouts/connection pool; automatic retries enabled.<br />
<strong>Fix</strong>: Set <code>connect/read</code> timeouts, pool size; disable automatic retries; enforce idempotency on critical writes.</p>
</li>
</ul>
<hr />
<h2 id="4-code-frontend-ruoyi-vue">4. Code &amp; Frontend (RuoYi + Vue)<a class="headerlink" href="#4-code-frontend-ruoyi-vue" title="Permanent link">&para;</a></h2>
<ul>
<li>
<p><strong>MyBatis <code>Invalid bound statement</code></strong><br />
<strong>Cause</strong>: <code>mapper-locations</code> or <strong>XML <code>namespace</code> ≠ interface FQN</strong>; XML not packaged.<br />
<strong>Fix</strong>: Align <code>@MapperScan + namespace</code>; ensure XML are scanned and packaged.</p>
</li>
<li>
<p><strong>Frontend CORS / port mismatch</strong><br />
<strong>Cause</strong>: Proxy not updated when switching environments.<br />
<strong>Fix</strong>: Unify proxy in <code>vue.config.js</code>; ports/targets switch with env variables.</p>
</li>
<li>
<p><strong>Minor UI issues (from phase summary)</strong><br />
<strong>Symptom</strong>: Area/map names wrap, status doesn’t auto-refresh, response structures inconsistent, etc.<br />
<strong>Fix</strong>:  </p>
</li>
<li>Adjust table column width + <code>tooltip</code>;  </li>
<li>Add “manual refresh” (add timed refresh later);  </li>
<li><strong>Robust parsing</strong> for API responses (“string/object”) to avoid misleading task dispatch hints;  </li>
<li>Missing <code>areaId</code> ↔ coordinates mapping → align with vendor data table, include in later milestones.</li>
</ul>
<hr />
<h2 id="5-conventions-governance-unified-naming-traceability">5. Conventions &amp; Governance (Unified Naming &amp; Traceability)<a class="headerlink" href="#5-conventions-governance-unified-naming-traceability" title="Permanent link">&para;</a></h2>
<ul>
<li><strong>Inconsistent resource names / log fields → hard to troubleshoot</strong><br />
<strong>Fix</strong>:  </li>
<li>Standardize resource naming (aligned with Sentinel rules) and unify exception bodies;  </li>
<li>Inject <code>traceId</code>, <code>requestId</code>, <code>taskId</code>, <code>resource</code> into logs;  </li>
<li>Postmortem process: <strong>deliver first, evolve later</strong>; leave traces for changes &amp; rollbacks; codify “Issue → Cause → Fix” into docs.</li>
</ul>
<hr />
<h3 id="appendix-reusable-checklist-pre-go-live-self-check">Appendix: Reusable Checklist (Pre-Go-Live Self-Check)<a class="headerlink" href="#appendix-reusable-checklist-pre-go-live-self-check" title="Permanent link">&para;</a></h3>
<ul>
<li>[ ] <code>gateway</code> routes/prefixes consistent with downstream paths;  </li>
<li>[ ] Nacos rules (DataId/Group) aligned with application resource names;  </li>
<li>[ ] SkyWalking <code>-javaagent</code> injected, Gateway/WebFlux plugins in place;  </li>
<li>[ ] Docker <code>healthcheck</code> complete; initial SQL auto-imported at first boot;  </li>
<li>[ ] Load-test definitions when consumers are off; for production enable consumers with DLQ;  </li>
<li>[ ] CORS, timeouts, connection pool, idempotency &amp; retry policies in place;  </li>
<li>[ ] Logs contain trace fields; support <strong>trace ↔ log</strong> cross-checks.</li>
</ul>
<blockquote>
<p>Metrics source: phase summary &amp; demo load-test records (baseline 100 QPS, P95 ≈ 6 ms, P99 ≈ 9–10 ms, Error = 0).</p>
</blockquote>












                
              </article>
            </div>
          
          
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
        </div>
        
          <button type="button" class="md-top md-icon" data-md-component="top" hidden>
  
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg>
  Back to top
</button>
        
      </main>
      
        <footer class="md-footer">
  
    
      
      <nav class="md-footer__inner md-grid" aria-label="Footer" >
        
          
          <a href="../loadtest-jmeter/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Load Test (JMeter)">
            <div class="md-footer__button md-icon">
              
              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
            </div>
            <div class="md-footer__title">
              <span class="md-footer__direction">
                Previous
              </span>
              <div class="md-ellipsis">
                Load Test (JMeter)
              </div>
            </div>
          </a>
        
        
      </nav>
    
  
  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      <div class="md-copyright">
  
    <div class="md-copyright__highlight">
      © 2025 陈峥 Jimmy Chen · <a href="/legal/license/">MIT License</a>
    </div>
  
  
    Made with
    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
      Material for MkDocs
    </a>
  
</div>
      
        
<div class="md-social">
  
    
    
    
    
    <a href="https://github.com/JimmyZChen" target="_blank" rel="noopener" title="GitHub" class="md-social__link">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2A10 10 0 0 0 2 12c0 4.42 2.87 8.17 6.84 9.5.5.08.66-.23.66-.5v-1.69c-2.77.6-3.36-1.34-3.36-1.34-.46-1.16-1.11-1.47-1.11-1.47-.91-.62.07-.6.07-.6 1 .07 1.53 1.03 1.53 1.03.87 1.52 2.34 1.07 2.91.83.09-.65.35-1.09.63-1.34-2.22-.25-4.55-1.11-4.55-4.92 0-1.11.38-2 1.03-2.71-.1-.25-.45-1.29.1-2.64 0 0 .84-.27 2.75 1.02.79-.22 1.65-.33 2.5-.33s1.71.11 2.5.33c1.91-1.29 2.75-1.02 2.75-1.02.55 1.35.2 2.39.1 2.64.65.71 1.03 1.6 1.03 2.71 0 3.82-2.34 4.66-4.57 4.91.36.31.69.92.69 1.85V21c0 .27.16.59.67.5C19.14 20.16 22 16.42 22 12A10 10 0 0 0 12 2"/></svg>
    </a>
  
    
    
    
    
    <a href="https://gitee.com/Jimmy-chen-zheng" target="_blank" rel="noopener" title="Gitee" class="md-social__link">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M11.984 0A12 12 0 0 0 0 12a12 12 0 0 0 12 12 12 12 0 0 0 12-12A12 12 0 0 0 12 0zm6.09 5.333c.328 0 .593.266.592.593v1.482a.594.594 0 0 1-.593.592H9.777c-.982 0-1.778.796-1.778 1.778v5.63c0 .327.266.592.593.592h5.63c.982 0 1.778-.796 1.778-1.778v-.296a.593.593 0 0 0-.592-.593h-4.15a.59.59 0 0 1-.592-.592v-1.482a.593.593 0 0 1 .593-.592h6.815c.327 0 .593.265.593.592v3.408a4 4 0 0 1-4 4H5.926a.593.593 0 0 1-.593-.593V9.778a4.444 4.444 0 0 1 4.445-4.444h8.296Z"/></svg>
    </a>
  
    
    
    
    
    <a href="mailto:chenzheng2024xm@163.com" target="_blank" rel="noopener" title="Email" class="md-social__link">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m20 8-8 5-8-5V6l8 5 8-5m0-2H4c-1.11 0-2 .89-2 2v12a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2V6a2 2 0 0 0-2-2"/></svg>
    </a>
  
    
    
    
    
    <a href="https://www.linkedin.com/in/jimmy-chen-74a8182b8/" target="_blank" rel="noopener" title="LinkedIn" class="md-social__link">
      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 3a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2zm-.5 15.5v-5.3a3.26 3.26 0 0 0-3.26-3.26c-.85 0-1.84.52-2.32 1.3v-1.11h-2.79v8.37h2.79v-4.93c0-.77.62-1.4 1.39-1.4a1.4 1.4 0 0 1 1.4 1.4v4.93zM6.88 8.56a1.68 1.68 0 0 0 1.68-1.68c0-.93-.75-1.69-1.68-1.69a1.69 1.69 0 0 0-1.69 1.69c0 .93.76 1.68 1.69 1.68m1.39 9.94v-8.37H5.5v8.37z"/></svg>
    </a>
  
</div>
      
    </div>
  </div>
</footer>
      
    </div>
    <div class="md-dialog" data-md-component="dialog">
      <div class="md-dialog__inner md-typeset"></div>
    </div>
    
    
    
      
      <script id="__config" type="application/json">{"base": "../..", "features": ["navigation.instant", "navigation.sections", "content.code.copy", "content.image.zoom", "content.image.lightbox", "toc.integrate", "navigation.footer", "navigation.top"], "search": "../../assets/javascripts/workers/search.973d3a69.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
    
    
      <script src="../../assets/javascripts/bundle.f55a23d4.min.js"></script>
      
        <script src="../../move-palette.js"></script>
      
    
  </body>
</html>